/**
 * @file cfg_utils.h
 * @brief 通用配置文件解析工具头文件
 * @details 本文件提供了通用的配置文件解析功能，支持cfg格式的配置文件。
 *          采用key=value格式，支持注释行（以#开头）。
 * 
 *          主要功能包括：
 *          - cfg文件加载：从cfg文件加载配置
 *          - cfg文件保存：将配置保存为cfg文件
 *          - 配置项解析：解析key=value格式的配置行
 *          - 注释处理：支持#开头的注释行
 *          - 字符串处理：自动去除首尾空格
 * 
 * @author zyb
 * @date 2025-09-25
 * @version 1.0
 * 
 * @note 本模块是通用的配置文件解析工具
 * @warning 配置文件格式必须严格遵循key=value格式
 */

#ifndef APP_UTILS_CFG_UTILS_H
#define APP_UTILS_CFG_UTILS_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 错误码定义 ==================== */

/**
 * @brief cfg操作结果类型
 * @details 定义cfg操作的各种结果状态
 */
typedef enum {
    CFG_SUCCESS = 0,                    /* 操作成功 */
    CFG_ERROR_INVALID_PARAM = -1,       /* 无效参数 */
    CFG_ERROR_FILE_NOT_FOUND = -2,      /* 文件未找到 */
    CFG_ERROR_PARSE_FAILED = -3,        /* 解析失败 */
    CFG_ERROR_SAVE_FAILED = -4,         /* 保存失败 */
    CFG_ERROR_MEMORY = -5,              /* 内存错误 */
    CFG_ERROR_UNKNOWN = -6              /* 未知错误 */
} cfg_result_t;

/* ==================== 配置项结构 ==================== */

/**
 * @brief 配置项结构
 * @details 表示一个配置项，包含key和value
 */
typedef struct {
    char key[128];      /* 配置项键名 */
    char value[256];    /* 配置项值 */
} cfg_item_t;

/* ==================== 104协议应用配置结构 ==================== */

/**
 * @brief 104协议配置结构
 */
typedef struct {
    char server_ip[16];        /* 104协议服务器IP地址 */
    uint16_t server_port;      /* 104协议服务器端口 */
} app_protocol_104_config_t;

/**
 * @brief 网络配置结构
 */
typedef struct {
    uint32_t timeout_ms;       /* 超时时间(毫秒) */
    uint32_t buffer_size;      /* 缓冲区大小 */
    bool auto_reconnect;       /* 自动重连 */
    uint32_t reconnect_interval; /* 重连间隔(秒) */
    uint32_t max_reconnect_count; /* 最大重连次数 */
    uint32_t heartbeat_interval; /* 心跳间隔(秒) */
} app_network_config_t;


/**
 * @brief 日志配置结构
 */
typedef struct {
    char log_path[256];             /* 日志文件基础路径 */
    uint32_t log_level;             /* 日志级别 */
    uint32_t max_file_size;         /* 最大文件大小(字节) */
} log_config_t;

/**
 * @brief 应用程序配置结构
 */
typedef struct {
    char app_name[64];         /* 应用程序名称 */
    char version[32];          /* 版本号 */
    app_protocol_104_config_t protocol_104; /* 104协议配置 */
    app_network_config_t network;  /* 网络配置 */
    log_config_t log;          /* 日志配置 */
    bool debug_mode;           /* 调试模式 */
} app_config_t;

/**
 * @brief 配置项回调函数类型
 * @details 用于处理解析到的配置项
 * 
 * @param key 配置项键名
 * @param value 配置项值
 * @param user_data 用户数据指针
 * @return 处理结果
 */
typedef cfg_result_t (*cfg_item_callback_t)(const char *key, const char *value, void *user_data);

/* ==================== 函数声明 ==================== */

/**
 * @brief 初始化cfg工具
 * @details 初始化cfg工具模块
 * 
 * @return 初始化结果
 */
int cfg_utils_init(void);

/**
 * @brief 销毁cfg工具
 * @details 清理cfg工具资源
 */
void cfg_utils_destroy(void);

/**
 * @brief 加载cfg配置文件
 * @details 从cfg文件加载配置，使用回调函数处理每个配置项
 * 
 * @param cfg_file cfg文件路径
 * @param callback 配置项处理回调函数
 * @param user_data 用户数据指针
 * @return 加载结果
 */
cfg_result_t cfg_utils_load_file(const char *cfg_file, cfg_item_callback_t callback, void *user_data);

/**
 * @brief 保存cfg配置文件
 * @details 将配置项保存为cfg格式文件
 * 
 * @param cfg_file cfg文件路径
 * @param items 配置项数组
 * @param item_count 配置项数量
 * @param header_comment 文件头注释（可为NULL）
 * @return 保存结果
 */
cfg_result_t cfg_utils_save_file(const char *cfg_file, const cfg_item_t *items, size_t item_count, const char *header_comment);

/**
 * @brief 解析cfg配置行
 * @details 解析key=value格式的配置行
 * 
 * @param line 配置行
 * @param key 输出键名
 * @param value 输出值
 * @return 解析结果
 */
cfg_result_t cfg_utils_parse_line(const char *line, char *key, char *value);

/**
 * @brief 检查是否为注释行
 * @details 检查行是否以#开头（注释行）
 * 
 * @param line 行内容
 * @return true: 是注释行, false: 不是注释行
 */
bool cfg_utils_is_comment_line(const char *line);

/**
 * @brief 去除字符串首尾空格
 * @details 修改原字符串，去除首尾空格
 * 
 * @param str 字符串指针
 */
void cfg_utils_trim_string(char *str);

/**
 * @brief 获取cfg错误信息
 * @details 获取最后一次cfg操作的错误信息
 * 
 * @return 错误信息字符串
 */
const char* cfg_utils_get_error(void);

/* ==================== 104协议应用配置管理 ==================== */

/**
 * @brief 初始化应用配置
 * @details 初始化应用配置模块，设置默认配置值
 * 
 * @return 初始化结果
 */
int app_config_init(void);

/**
 * @brief 加载应用配置文件
 * @details 从cfg文件加载104协议应用配置
 * 
 * @param config_file 配置文件路径
 * @return 加载结果
 */
cfg_result_t app_config_load(const char *config_file);

/**
 * @brief 保存应用配置文件
 * @details 将当前应用配置保存为cfg文件
 * 
 * @param config_file 配置文件路径
 * @return 保存结果
 */
cfg_result_t app_config_save(const char *config_file);

/**
 * @brief 获取应用程序配置
 * @details 获取当前的应用程序配置
 * 
 * @param config 配置结构指针
 * @return 获取结果
 */
cfg_result_t app_config_get(app_config_t *config);

/**
 * @brief 设置应用程序配置
 * @details 设置应用程序配置参数
 * 
 * @param config 配置结构指针
 * @return 设置结果
 */
cfg_result_t app_config_set(const app_config_t *config);

/**
 * @brief 验证配置参数
 * @details 验证配置参数的有效性
 * 
 * @param config 配置结构指针
 * @return 验证结果
 */
cfg_result_t app_config_validate(const app_config_t *config);

/**
 * @brief 重置为默认配置
 * @details 将所有配置参数重置为默认值
 * 
 * @return 重置结果
 */
cfg_result_t app_config_reset_defaults(void);

/**
 * @brief 获取网络配置
 * @details 获取网络配置参数
 * 
 * @param network_config 网络配置结构指针
 * @return 获取结果
 */
cfg_result_t app_config_get_network(app_network_config_t *network_config);

/**
 * @brief 设置网络配置
 * @details 设置网络配置参数
 * 
 * @param network_config 网络配置结构指针
 * @return 设置结果
 */
cfg_result_t app_config_set_network(const app_network_config_t *network_config);

/**
 * @brief 获取104协议配置
 * @details 获取104协议配置参数
 * 
 * @param protocol_104_config 104协议配置结构指针
 * @return 获取结果
 */
cfg_result_t app_config_get_protocol_104(app_protocol_104_config_t *protocol_104_config);

/**
 * @brief 设置104协议配置
 * @details 设置104协议配置参数
 * 
 * @param protocol_104_config 104协议配置结构指针
 * @return 设置结果
 */
cfg_result_t app_config_set_protocol_104(const app_protocol_104_config_t *protocol_104_config);

/**
 * @brief 获取日志配置
 * @details 获取日志配置参数
 * 
 * @param log_config 日志配置结构指针
 * @return 获取结果
 */
cfg_result_t app_config_get_log(log_config_t *log_config);

/**
 * @brief 设置日志配置
 * @details 设置日志配置参数
 * 
 * @param log_config 日志配置结构指针
 * @return 设置结果
 */
cfg_result_t app_config_set_log(const log_config_t *log_config);

/**
 * @brief 销毁应用配置
 * @details 清理应用配置资源
 */
void app_config_destroy(void);

#ifdef __cplusplus
}
#endif

#endif /* APP_UTILS_CFG_UTILS_H */
